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SUMMARY 


Previously,  Naval  technical  documentation  standards  have  been  develo^d  using  a  static,  top-down, 
structured  approach  that  is  oriented  toward  lanquaqes  such  as  COBOL  and  FORTRAN.  Because  the  Navy 
Occupational  Health  Information  Management  System  (NOIIIHS)  uses  the  Massachusetts  General  Hospital 
Utility  Mu  It i- Programming  System  (MUMPS)  language,  which  is  dynamic  in  nature,  it  was  felt  that  new 
technical  documentation  standards  had  to  he  developed  to  accomodate  its  flexibility.  This  paper 
describes  a  transactional  approach  to  documentat ing  the  NOHIMG  system.  examples  of  documentation 
worksheets,  as  well  as  a  diagram  depicting  the  levels  of  documentation  and  their  relationship  to  the 
transaction  center,  are  provided.  This  method  of  documentation  may  be  advantageous  for  others  who 
are  working  with  dynamic  or  evolving  systems. 
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BACKGROUND 


At  the  Naval  Health  Research  Center  (HHRC),  Point  Loma,  California,  the  Navy  Occupational  Health 

In  roririat  ion  Management  System  (NOHIMS)  is  being  developed  for  the  Navy's  Occupational  Health  and 
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Safety  Program.  '  Because  it  is  being  developed  as  a  research  project,  it  is  a  dynamic  system  with 
qoals  that  chanqe  as  the  system  evolves.  To  accomodate  the  dynamic  nature  of  the  project,  MUMPS  was 
selected  as  the  programming  lanquage  for  the  NOHIMS  effort.  MUMPS’  unique  data  management  system  was 
designed  to  be  used  in  the  development  of  complex,  interactive  application  systems.'*  In  contrast  to 

other  high  level  languages,  MUMPS  allows  the  application  designer  flexibility  when  handling  data  with 
...  4 

imprecise  specifications. 

Although  NOHIMS  has  been  running  successfully  at  the  Navel  Air  Rewock  Facility,  Naval  Air 
Station,  North  Island,  the  continued  operation  and  maintenance  of  NOHIMS  requires  that  the  system  be 
documented.  Current  Navy  documemtat ion  standards  ^  were  reviewed  and  appeared  to  be  oriented  toward 
languages  such  as  Cobol  and  Fortran. 

The  Navy  technical  documentation  standards  are  defined  using  four  documents;  Data  Base 
Specifications,  System  or  subsystem  Specifications,  Program  Specifications,  and  a  Maintenance  Manual. 
This  standard  assumes  that  the  system  will  be  designed  using  a  top-down  approach.  Program 
Specifications  describe  detailed,  well  structured  programs  that  call  single  task  modules  to  perform 
system's  functions  or  subfunctions,  outlined  in  the  System  or  Subsystem  Specifications.  Data  base 
requirements  and  data  flows  are  completey  defined  prior  to  beginning  the  programming  of  the  system. 
The  Maintenance  Manual  is  described  as  an  update  or  amplification  of  the  Program  Specification. 
Using  the  top-down  approach  to  describe  a  system,  and  documenting  it  a?  such,  works  well  within  a 
closed  system.  However,  this  approach  is  oriented  toward  a  fixed  goal  and,  as  such,  does  not  take 
into  consideration  the  following  factors: 

1.  The  system  may  have  multiple  goals. 

2.  New  data  elements  may  be  needed  at  a  later  time. 

3.  Tf.3  set  of  operations  to  complete  various  procedures  may  undergo 
re-def  1  nit  ion. 

4.  In  a  dynamic  system,  it  is  nearly  impossible  to  predict  how  the  data 
will  be  used  in  the  future. 
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Therefore,  MUMPS  provided  the  software  environment  that  allowed  the  dynamic  nature  of  NOH1MS  to  be 
met,  but  a  new  documentation  approach  was  needed.  The  purpose  of  this  paper  is  to  describe  tne 
approach  taken  at  NHRC  to  develop  the  documentation  needed  to  operate  and  maintain  NOHIMS.  It  is 
believed  that  the  approach  used  is  general  and  is  applicable  for  other  MUMPS-based  systems, 

APPROACH 

The  approach  taken  to  develop  documentation  standards  for  NOHIMS  was  a  transactional  approach. 
According  to  Yourdon  and  Constantine,^  transaction  analysis  is  used  to  describe  complex  systems  in 
which  a  variety  of  different  options  can  be  selected  from  a  central  point..  As  a  rule  this  central 
point,  or  transaction  center,  occupies  the  upper  level  of  the  system.  Transactions  are  initiated  by 
calling  lower  level  routines  or  modules  to  initiate  a  transaction.  However,  in  large,  complex 
systems,  the  transaction  center  may  be  at  a  lower  level  than  the  function  it  calls.  There  may  al30 
be  transaction  centers  at  lower  levels,  called  actic  ievels,  and  these  are  referred  to  as  action 
centers . 

A  transaction  or  action  center  is  the  point  where  transactions  or  processes  aie  initiated  and 
ultimately  return.  A  center  is  found  by  locating  the  point  at  which  data  is  transformed  as  a 
function  of  a  module  by  splitting  input  data  into  several  discrete  output  streams. 

By  using  this  strategy,  the  documentation  specifications  emphasize  the  data  flows  rather  than 
the  actual  coding  or  program  structure.  Thus,  the  technical  documentation  can  be  condensed  into  one 
document,  the  Maintenance  Manual,  which  consists  of  the  Module  Documentation,  Test  Documentation,  and 
Special  Notes.  This  document  is  a  technical  tool  for  programmers  and  analysts  who  are  responsible 
for  ongoing  software  support  after  the  system  is  operational.  Its  purpose  is  to  aid  analysts  and 
programmers  when  they  troubleshoot  problems  or  when  they  need  to  revise  or  modify  the  system. 

Therefore,  the  documentation  required  for  NOHIMS  consists  cf  user,  operator,  and  technical 
documentation.  The  user  and  operator  documentation  provides  non-technical  personnel  with  information 
regarding  the  objectives  of  a  system,  the  functions  it  performs,  and  how  to  use  it.  Thus,  the  user 
and  operator  documentation  is  not  unique  for  MUMPS.  However,  the  technical  documentation  is  unique 
because  it  accomodates  MUMPS'  flexibility. 

TECHNICAL  DOCUMENTATION 

Technical  Documentation  standards  developed  for  NOHIMS  is  a  transactional  approach  to 
documentation.  A  system  may  be  designed  which  consists  of  only  two  levels;  a  main  driver  and  a 
transaction  center.  However,  most  systems  have  sufficient  complexity  to  warrant  intermediate  levels 
ol'  documentation.  In  the  documentation  standard  developed  for  NOHIMS,  four  levels  have  been  defined. 
These  levels  are  processor,  transaction,  action,  and  routine.  The  relationship  among  these  levels  is 
shown  in  figure  1. 


The  Processor  level  is  the  first  level  of  a  system.  At  the  processor  level,  the  primary  system 
functions  are  identified.  Transactions  are  received  and  dispatched  to  the  appropriate  transaction 
level  for  processing. 

The  Transaction  level  is  the  second  level  of  the  system  where  all  subfunctions  of  the  system  are 
defined  in  terms  of  processes  or  operations.  If  a  module  performs  many  subfunctions  or  complex 
operations,  it  should  be  separated  into  two  or  more  action  level  modules. 

The  Action  level  describes  the  aggregate  of  operations,  procedures,  or  routines  that  occur 
within  each  transaction.  When  the  transaction  is  lengthy  or  complicated,  the  transaction  is 
separated  into  smaller  components  called  actions. 

The  Routine  level  is  the  lowest  level  in  the  system.  It  is  the  actual  coding  level  and  is 
responsible  for  carrying  out  the  details  of  the  actionB  required  to  complete  the  transaction.  Ont  of 
the  purposes  of  creating  small,  loosely  coupled,  internally  cohesive  routines  is  to  facilitate 
programming  design,  system  implementation,  and  subsequent  maintenance  or  revisions.  Routines  should 
be  functionally  separate  so  that  each  performs  a  specific  task  or  a  few  closely  related  tasks  that  no 
other  routine  performs. 


DOCUMENTATION  SPECIFICATIONS 


Every  level  has  a  specific  iocumcntat  ion  requirement.  The  processor  spec  it  ic.it  ion  is  a  detailed 
technical  document  prepared  by  an  analyst  for  the  use  of  programmers  in  writing  modules  needed  to 
implement  a  project.  It  describes  the  data  to  be  input,  the  transactions  to  be  performed,  and  the 
data  to  be  output.  It  also  provides  important  and  related  information  such  as  disposition  of  data, 
security  classification  requirements,  and  the  relationship  of  each  transaction  module  to  other 
modules  in  the  same  system  or  in  other  systems. 

The  Transaction  Specification  is  a  detailed  technical  document  prepared  by  an  analyst  for 
programmers  to  use  when  writ-.tg  the  transaction  modules.  It  describee  the  data  entry  and  exit 
points.  It  also  provides  important  and  related  information  such  as  transformations  of  data,  and  the 
relationship  of  each  transaction  module  to  other  modules  in  the  system.  Transaction  specification 
documental  ior,  is  divided  into  four  sections  which  are  designated  the  Transaction  summary.  Summary  of 
Pequ  i  rements,  Environmental  Description,  and  Design  Details.  To  assist  the  user  in  the  development 
of  the  required  documentation,  various  work  sheets  have  been  developed.  Work  sheets  developed  to 
assist  the  Transaction  Summary  and  Summary  of  Requirements  documentation  are  shown  in  figures  2  ar.d 
3. 


The  Action  Specification  is  written  by  the  programmer  and  references  the  transaction.  It 
describes  the  data  to  be  input,  output  and  transformed  in  this  module.  It  also  provides  important 
and  related  information  such  as  the  relationship  of  each  action  module  to  other  module  levels  in  the 
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system.  Documentation  at  the  Action  level  is  broker  down  into  tour  sections.  inese  include  the 
Action  Summary,  Summary  of  Requirements,  process  Cross  Reference  Page,  and  Design  Details.  Again, 
work  sheets  similar  to  those  used  for  the  Transaction  level  are  available. 

The  Routine  s  pec  i  f  icat  i  on  is  a  detailed  technical  docui-.ort  prepared  by  the  programmer  to  meet 
the  specifications  defined  by  the  analyst.  It  describes  the  function  of  the  routine,  data  to  be 
manipulated,  operations  to  be  performed,  and  the  relationship  of  the  routine  to  other  module  levels. 
Oniy  data  that  is  critical  to  the  understanding  to  the  routine  need  he  described  in  detail.  Routine 
documentation  consists  of  the  Routine  Abstract,  Summary  of  Requirements,  Software  Support,  and  Design 
Documentation.  The  work  sheets  provided  for  Routine  document at  ion  includes  one  for  the  Routine 
Abstract,  one  for  the  Summary  of  Requirements,  and  one  for  listing  critical  variables.  The  work 
sheet  for  developing  Routine  Abstract  information  is  essentially  the  same  as  the  one  shown  in  figure 
2  for  Transaction  Summary  documentat i on .  However,  the  work  sheets  shown  in  figures  4  and  5  are 
unique  to  the  Routine  Specification. 


CONCLUSION 


Just  as  MUMPS  is  designed  to  accomodate  dynamic  environments  where  goals  and  data  elements  may 
be  changing  over  time,  the  documentation  method  developed  for  NOHIMS  is  designed  to  be  flexible. 
Thus,  this  method  of  documentation  nay  be  advantageous  for  others  who  are  working  with  developmental, 
dynamic  or  evolving  systems. 
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DISPOSITION  OF  OUTPUT! 

INPUTS  TO  TRANSACTION: 

RETENTION  PERIOD:  _ 

SECURITY/PRIVACY :  _ 

NOTES :  _ 


Figure  2.  Work  sheet  for  documenting  Summary  information  at  the  Tran-action  level. 
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TRANSACTION  SUMHARY  REQUIREMENTS 

SYSTEM: _ OATEs 

SYSTEM  FUNCTION:  _ _ _  PAGE: 

SYSTEM  SUBFlINCTION/TRANSACTIONi _ 


TRANSACTION  DESCRIPTION: 


Figure  3.  Worksheet  for  documenting  requirement*  at  transaction 
level . 
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ROUTINE  LEVEL  SUMMARY  OF  REOU) RKMFNTS 


SYSTEM:  _ 

ROUTINE:  _ 

ROUTINE  DESCRIPTION: 


LIST  OF  CRITICAL  VARIABLES: _ _ 

DESCRIPTION  OF  ERROR  CRITERIA  AND  RECOVERY! 


DATE: 

REV.lt 


NOTES: 


Figure  4.  Worksheet  for  documenting  requirements  »t  the  Routine 
level . 
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LIST  OF  CRITICAL  VARIABLES 


ROUTINE: _ PAGF  _  of 

NAME  OF  VARIABLE: _ _ _ 

DESCRIPTION:  _ 

SPECIFICATIONS:  _ 


SOURCE  OF  VARIABLE: 

NAME  OF  VARIABLE: 

DESCRIPTION:  _ 

SPECIFICATIONS: 


SOURCE  OF  VARIABLE: 

NAME  OF  VARIABLE:  _ 

DESCRIPTION:  _ 

SPECIFICATIONS: 


SOURCE  OF  VARIABLE: 

NAME  OF  VARIABLE: 

DESCRIPTION:  _ 

SPECIFICATIONS : 


SOURCE  OF  VARIABLE: 


Figure  5.  Workahett  for  documenting  the  critical  variables  at  the 
Rout  in*  level  - 
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